fail2ban — 入侵防御自动化封禁详解

fail2ban 是一个用 Python 编写的开源入侵防御工具（HIDS/IPS）。它扫描日志文件（如 /var/log/auth.log），一旦发现同一 IP 在短时间内出现多次认证失败，就通过修改系统防火墙规则（iptables / nftables / ipset 等）把该 IP 拒之门外，并在可配置的时间后自动解封。它开箱即可读懂 sshd、Apache、nginx 等几十种常见日志，也能轻易接入任何自研应用的日志。

本页先梳理 fail2ban 的"是什么"与行为/结构，再给出实战操作手册与参数指令速查。

1. 概述

1.1 是什么

fail2ban（f2b）由 Cyril Jaquier 于 2004 年编写，GPL v2 协议，当前由社区维护（v1.x，代码托管在 github.com/fail2ban/fail2ban）。它由三个可执行组件构成：

• fail2ban-server — 常驻后台的守护进程（daemon），真正干活：读日志、计数、封禁、解封。
• fail2ban-client — 控制客户端，通过 Unix socket 与 server 通信，负责查看状态、启停、手动封禁/解封、热重载配置等。官方强烈建议：永远通过 fail2ban-client 操作，绝不要直接调用 fail2ban-server。
• fail2ban-regex — 正则测试工具，写 filter 前先用它验证 failregex 能否正确匹配日志。

核心数据结构是 Jail（监狱）：每一个被保护的服务（如 sshd、apache）就是一个 jail，里面定义了"看哪个日志、怎么判定失败、失败多少次封禁、用什么方式封禁、封多久"。fail2ban 会为每个 jail 起一个独立线程持续运转。

1.2 核心心智模型：Jail = Filter + Action

记住一句话：Jail（监狱）＝ Filter（过滤器，负责"判罪"）+ Action（动作，负责"执行刑罚"）+ 判决参数（bantime / findtime / maxretry）。

# 一条典型日志行（sshd 认证失败）
Feb  3 14:11:15 host sshd[25076]: Failed password for invalid user admin from 203.0.113.7 port 53526 ssh2

# 流程：datepattern 去掉时间 → failregex 匹配失败模式并抠出 IP
# failregex 得到  = 203.0.113.7 → 在 findtime(如10m) 内累计 ≥ maxretry(如5次) → 封禁 bantime(如1h)

四个"时间/次数"参数是所有 jail 的公共语言：

• findtime — "回看窗口"：fail2ban 只统计最近 N 秒内发生的失败。
• maxretry — 窗口内失败次数达到该值就触发封禁。
• bantime — 封禁持续时长，到期自动解封。
• maxmatches — 每条封禁票据内存中保留的匹配日志行数。

1.3 生态与位置：IDS/IPS/防火墙

要理解 fail2ban 在安全体系中的位置，先分清这些角色：

• IDS（Intrusion Detection System，入侵检测系统） — 只"看"不"拦"，发现异常报警。
• IPS（Intrusion Prevention System，入侵防御系统） — 检测到攻击后主动阻断。fail2ban 更接近 IPS，因为它真的会改防火墙规则封禁。
• HIDS（Host-based IDS/IPS） — 部署在单台主机上的检测/防御系统（相对 NIDS 部署在网络边界）。fail2ban 是典型的 HIDS。
• 防火墙（Firewall） — 内核级网络过滤（iptables/nftables），fail2ban 本身不负责过滤，而是指挥防火墙按需增减规则。
• backend（后端） — fail2ban 发现"日志有新内容"的机制：pyinotify（内核 inotify 事件，最高效）、polling（轮询，无依赖）、systemd（直接读 systemd journal）。

1.4 安装方式

环境要求：Python ≥ 3.5（可选依赖 pyinotify、python-systemd、dnspython）。源码安装：

git clone https://github.com/fail2ban/fail2ban.git
cd fail2ban
sudo python setup.py install
# 自检与版本确认
fail2ban-client -h
fail2ban-client version

启动与开机自启（systemd 发行版）：

sudo systemctl enable --now fail2ban
sudo systemctl status fail2ban

2. 行为图（系统"做什么"）

2.1 用例图 — 交互全景

从外部视角看，谁在与 fail2ban 打交道：管理员通过 client 控制它；攻击者持续失败登录"喂"它；它则指挥防火墙、发通知。

图 2.1 用例图 — fail2ban 交互全景

2.2 活动图 — 从日志到封禁主流程

这是 fail2ban 的核心主流程：读日志 → 三层正则过滤 → 计数 → 到阈值 → 封禁 → 到期解封。

图 2.2 活动图 — 一条日志行从读取到封禁/忽略的判定主流程

代码演示：三条 filter 规则如何层层把关

# filter.d/sshd.conf 中的判定链
[Definition]
prefailregex = ^<F-MLFID>%(__prefix_line)s<F-MLFID/>(?: %(__sshd_exclude)s)?(?: \\[pid <F-ID>\\d+<F-ID/>\\])? \
               <F-CONTENT>.+</F-CONTENT>$
failregex = ^%(__prefix_line)s(?:error: )?Received disconnect from <HOST>.*: 3: .*: Auth fail$
            ^%(__prefix_line)sInvalid user <USER> from <HOST> port $
            ^%(__prefix_line)s(?:error: )?pam_unix\(sshd:auth\): authentication failure; logname=.* uid=.* euid=.* tty=.* ruser=.* rhost=<HOST>
ignoreregex =

2.3 时序图 — 攻击→封禁→解封

把一次完整的攻击生命周期画成时序：攻击者失败登录 → sshd 写日志 → fail2ban 读到并计数 → 触发 actionban → 防火墙拒绝 → bantime 到期 → actionunban 恢复。

图 2.3 时序图 — 一次暴力攻击从发生到被封禁再到自动解封

2.4 状态机图 — 失败票据与封禁生命周期

一个 IP 在 fail2ban 内部的"案底"演化：从累积失败（Ticket）到被判刑（BanTicket），再到刑满释放（unban），或通过 recidive / increment 越封越重。

图 2.4 状态机图 — 失败票据与封禁的生命周期

3. 结构图（系统"由什么组成"）

3.1 部署图 — 生产部署拓扑

先看宏观部署：fail2ban 的 client/server 如何用 socket 通信，server 又连接了哪些外部资源（日志、防火墙、sqlite、SMTP、DNS）。

图 3.1 部署图 — 一台服务器上的 fail2ban 生产部署拓扑

3.2 组件图 — 内部模块

再看进程内部：fail2ban 是 Python 源码，client 与 server 分离，server 内部按职责拆分为 filters、regex、failmanager、banmanager、actions、database 等模块。

图 3.2 组件图 — fail2ban 内部模块协作

3.3 包图 — /etc/fail2ban 配置布局

fail2ban 的"四个配置文件类型"：fail2ban.conf（全局）、jail.conf（监狱）、filter.d/*.conf（过滤器）、action.d/*.conf（动作）。配置有严格的覆盖优先级。

图 3.3 包图 — 配置目录布局与加载优先级

代码演示：只改一个文件启用默认 sshd 监狱

# 创建 /etc/fail2ban/jail.local，仅写想改的项即可
[sshd]
enabled = true
maxretry = 5
findtime = 10m
bantime = 1h

3.4 类图 — 核心类结构

最后细化到核心类：JailThread 是每个监狱的运转线程，持有 Filter、FailManager、BanManager、Actions；通过 Transmitter 接收 client 命令。

图 3.4 类图 — fail2ban 核心类结构与关系

4. 实战操作手册

4.1 安装与启动

# Debian/Ubuntu
sudo apt update && sudo apt install -y fail2ban

# 启动并开机自启
sudo systemctl enable --now fail2ban

# 确认进程与版本
systemctl status fail2ban
fail2ban-client version          # v1.x
fail2ban-client ping             # 返回 pong 说明 server 存活

4.2 基础配置：启用 sshd 监狱

永远不要直接编辑 /etc/fail2ban/jail.conf（升级会被覆盖）。新建 jail.local：

# /etc/fail2ban/jail.local
[DEFAULT]
# 全局默认：10分钟内失败5次，封禁1小时
bantime  = 1h
findtime = 10m
maxretry = 5
# 永不封禁自己的/内网/办公出口 IP（用逗号分隔，支持 CIDR）
ignoreip = 127.0.0.1/8 ::1 192.168.0.0/16 10.0.0.0/8
# 默认封禁动作：按多端口写 iptables 规则（IPv4+IPv6 自动）
banaction = iptables-multiport
# 有 SMTP 的话可加邮件通知
# action = %(action_mwl)s   # 会同时调用 sendmail 发通知

[sshd]
enabled = true

应用配置并验证：

sudo systemctl reload fail2ban          # 热重载（不重启 server）
fail2ban-client status                  # 列出所有监狱
fail2ban-client status sshd             # 查看 sshd 监狱详情

4.3 自定义 Filter（新应用接入）

以监控自研应用（如后端 API 的登录接口）为例：日志形如 2026-08-20 10:00:01 ERROR login failed ip=203.0.113.9 user=admin。

# 1) 新建过滤器 /etc/fail2ban/filter.d/myapp.conf
[Definition]
# 匹配失败日志并抠出 IP； 是内置的"IP或主机名"正则
failregex = ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} ERROR login failed ip=<HOST> 
ignoreregex = ^.*user=(?:test|root)$     # 测试账号失败不封禁

# 2) 新建监狱 /etc/fail2ban/jail.local 追加
[myapp]
enabled  = true
filter   = myapp
logpath  = /var/log/myapp/api.log
backend  = polling
maxretry = 3
findtime = 5m
bantime  = 10m

先用 fail2ban-regex 验证正则（见 4.7），再 reload：

sudo systemctl reload fail2ban
fail2ban-client status myapp

4.4 自定义 Action（封禁+通知）

默认的 iptables-multiport 只做"DROP"，可以再加动作：邮件通知、调 webhook、或自定义命令。

# /etc/fail2ban/action.d/mywebhook.local
[Definition]
actionban   = curl -s -X POST http://alert.example.com/ban \
              -d 'ip=<ip>&count=<bancount>&jail=<name>'
actionunban = curl -s -X POST http://alert.example.com/unban \
              -d 'ip=<ip>&jail=<name>'
actionstart = echo "jail <name> started at <time>" 
actionstop  = echo "jail <name> stopped at <time>"

# jail.local 里给 sshd 同时挂默认防火墙动作 + 通知动作（可挂多个）
[sshd]
enabled   = true
action    = iptables-multiport[name=sshd, port="ssh", protocol=tcp]
            mywebhook

动作命令通过 shell 执行，<ip>、<name>、<time>、<failures>、<matches>、<bancount> 等标签会被自动替换（完整标签见 5.4）。

4.5 日常运维命令

fail2ban-client status                      # 全部监狱状态
fail2ban-client status sshd                 # 单个监狱：封禁列表/失败统计
fail2ban-client status --all                # 详细模式
fail2ban-client stats                       # 全部监狱统计表格
fail2ban-client set sshd bantime 2h         # 热修改封禁时长
fail2ban-client set sshd banip 203.0.113.9  # 手动立即封禁一个 IP
fail2ban-client set sshd unbanip 203.0.113.9   # 手动解封
fail2ban-client unban --all                 # 清空全部封禁
fail2ban-client get sshd banned             # 列出该监狱封禁的 IP
fail2ban-client reload                      # 热重载配置
fail2ban-client restart                     # 重启整个 server
fail2ban-client set loglevel DEBUG          # 临时调日志级别调试

4.6 进阶：渐进封禁与 recidive

对付顽固攻击者：bantime.increment 让封禁时长逐次翻倍；recidive 监狱专门"封禁那些反复被其他监狱封禁的 IP"。

# jail.local 开启渐进封禁（全部监狱生效）
[DEFAULT]
bantime.increment = true
bantime.factor    = 2        # 每次翻倍
bantime.maxtime   = 1w       # 封禁时长上限
bantime.random    = true     # 加入随机扰动防规律
bantime.overalljails = true  # 跨监狱累计次数

# recidive 监狱：24h 内被其它监狱封禁 ≥3 次的 IP，直接封 1 周
[recidive]
enabled = true
logpath = /var/log/fail2ban.log
banaction = iptables-allports
bantime  = 1w
findtime = 1d
maxretry = 3

4.7 正则测试：fail2ban-regex

写正则最容易出错，务必先用工具验证再上线：

# 用法: fail2ban-regex <LOG> <REGEX> [IGNOREREGEX]
# LOG 可以是：日志文件路径 / systemd-journal / 单行字符串
fail2ban-regex /var/log/auth.log '^.*Failed password for invalid user admin from <HOST> port '
fail2ban-regex /var/log/auth.log /etc/fail2ban/filter.d/sshd.conf
fail2ban-regex '2026-08-20 10:00:01 ERROR login failed ip=203.0.113.9' \
  '^.*login failed ip=<HOST> '

# 常用选项
# -r/--raw      不解析 DNS，只看 IP
# --usedns=no   只匹配 IP 不匹配主机名
# -d PATTERN    自定义 datepattern
# -L N          多行正则的 maxlines
# -o 'ip,msg'   只输出 ip 和 msg 字段
fail2ban-regex --usedns=no -r /var/log/auth.log sshd

输出会告诉你：Successfully matched（成功匹配数）与 Date / IP / Host 命中统计。只要 Successfully matched > 0 且 IP 列正确，这个 filter 才能用。

5. 参数指令速查手册

5.1 fail2ban-client 命令一览

5.2 jail.conf 参数表

5.3 filter.d 参数表

正则内建标签：

5.4 action.d 参数表与标签

命令中可替换的标签（<ip>、<time> 等）：

5.5 时间缩写格式

bantime、findtime 等时间参数既可用整数秒，也可用缩写：

可组合：1d12h30m；注意 m/mm 是分钟，月份要用 mo/mon。换算验证：

fail2ban-client --str2sec 1d12h     # 输出 129600

6. 故障排查与常见问题

7. 参考资料

• 官方站点：https://www.fail2ban.org
• 源码仓库：https://github.com/fail2ban/fail2ban
• Wiki / FAQ / HOWTO：https://github.com/fail2ban/fail2ban/wiki
• 开发者文档：https://fail2ban.readthedocs.io/
• man 手册：fail2ban-client(1)、fail2ban-server(1)、fail2ban-regex(1)、fail2ban.conf(5)、jail.conf(5)